Ultra Tools Image Load
======================

1. 노드의 목적
---------------
Ultra Tools Image Load는 ComfyUI Core의 Load Image를 기반으로 하면서,
input 폴더와 사용자가 등록한 output 하위 폴더의 이미지를 썸네일 또는 파일명 목록으로
찾아 선택할 수 있게 보완한 노드입니다.

input 이미지의 로드·업로드, IMAGE/MASK 출력과 파일 변경 감지는 현재 설치된 ComfyUI
Core Load Image의 동작을 사용합니다. 외부 이미지는 등록된 폴더 안의 파일인지 별도로
검증한 뒤 Core Load Image와 같은 방식으로 읽어 IMAGE/MASK를 출력합니다.


2. 기본 사용법
---------------
image 칸을 클릭하면 Core Load Image와 같이 파일명이 나열됩니다.
파일명을 직접 선택하면 즉시 노드 하단 미리보기에 표시됩니다.

choose file to upload 버튼은 Core Load Image와 같은 업로드 버튼입니다.
컴퓨터에서 파일을 선택하면 ComfyUI input 폴더에 업로드되고 노드에 적용됩니다.


3. View Input Thumbnails / input 썸네일 보기
------------------------------------------------
input 썸네일 보기 버튼을 누르면 ComfyUI input 폴더와 사용자가 등록한 외부 폴더의
이미지를 함께 탐색할 수 있는 이미지 브라우저가 열립니다.

- 썸네일 보기와 리스트 보기를 전환할 수 있습니다.
- 파일명 검색과 폴더 선택을 사용할 수 있습니다. 폴더 필터의 전체 이미지는 input
  루트·하위 폴더와 등록된 모든 외부 폴더의 이미지를 함께 표시한다는 뜻입니다.
- 최신 ComfyUI의 해시 기반 이미지 목록에서도 화면에 표시되는 경로를 기준으로 하위
  폴더를 구분합니다. 하위 폴더가 하나도 없으면 폴더 필터는 자동으로 숨겨집니다.
- 창의 가장자리를 끌어 브라우저 크기를 조절할 수 있습니다.
- 썸네일 크기를 슬라이더로 조절할 수 있습니다.
- 브라우저 창 크기, 보기 방식과 썸네일 크기는 다음 사용을 위해 기억됩니다.
- 브라우저의 글꼴과 크기는 현재 ComfyUI 노드 글꼴 설정을 따릅니다.
- 하단 선택 후보에는 파일명과 이미지 해상도가 함께 표시됩니다.
- 화면보다 몇 줄 아래의 썸네일까지 미리 불러와 초기 부하와 빠른 스크롤 시 대기를
  함께 줄입니다.
- 가로·세로 비율이 다른 이미지도 잘리지 않고 썸네일 영역 안에 전체가 표시됩니다.

브라우저에서 이미지를 한 번 클릭하면 선택 후보로만 표시되며 노드에는 아직 적용되지
않습니다. 하단의 Select/선택 버튼이 활성화된 뒤 그 버튼을 눌러야 노드의 image 값과
미리보기가 변경되고 브라우저가 자동으로 닫힙니다.
선택 직후에는 축소·캐시된 미리보기를 사용하여 노드 이미지도 즉시 갱신됩니다.

여러 이미지를 정리할 때는 Ctrl(Windows/Linux) 또는 Command(macOS)를 누른 채 클릭하면
개별 이미지를 선택 목록에 추가하거나 해제할 수 있습니다. Shift+클릭은 마지막 선택
위치부터 현재 이미지까지 범위로 선택합니다. 여러 장이 선택되어도 하단 선택 버튼은
마지막으로 선택한 한 장을 노드에 적용하며, 선택된 전체 목록은 일괄 삭제에 사용됩니다.

이미지를 더블 클릭하면 선택 후보 확인과 선택 버튼 단계를 생략하고 즉시 노드에
적용할 수 있습니다.

썸네일 이미지를 우클릭하면 원본 전용 메뉴가 열립니다. 새 탭에서 열기, 다른 이름으로
저장, 이미지 복사 모두 축소 썸네일이 아니라 원본 해상도 이미지를 대상으로 합니다.
이 세 동작은 우클릭한 한 장만 대상으로 하며 메뉴에 대상 파일명이 함께 표시됩니다.
선택한 이미지 삭제는 현재 선택된 모든 이미지를 대상으로 합니다. ComfyUI input 이미지와
등록된 외부 폴더 이미지 모두 실제 원본 파일이 영구 삭제되므로, 삭제 전에 표시되는
선택 개수와 전체 파일명 목록을 반드시 확인하십시오. 현재 노드에서 사용 중인 이미지가
포함되면 삭제 후 노드의 이미지 선택과 미리보기가 해제됩니다. 아직 등록하지 않은 폴더를
탐색하는 중에 표시되는 미리보기 이미지는 일괄 삭제 대상에 포함되지 않습니다.
열기·저장·복사에서는 해당 동작을 선택할 때만 원본 파일을 불러오므로 평상시 썸네일
탐색 속도에는 영향을 주지 않습니다.

브라우저 창 닫기, 우측 상단 X 또는 Esc로 닫으면 노드의 기존 이미지는 변경되지
않습니다. 창 바깥쪽을 클릭해도 브라우저는 닫히지 않습니다.

외부 이미지를 한 번만 사용하거나 input 폴더 안에 복사해 관리하려면 노드에 있는 Core의
choose file to upload 버튼을 사용합니다. 원래 위치의 파일을 복사하지 않고 계속 직접
불러오려면 아래의 외부 폴더 기능을 사용합니다(2.0.2부터 ComfyUI output 폴더 안만 가능).

IMAGE 입력 단자에서 연결선을 놓아 기존 LiteGraph 추천 메뉴를 열면 Ultra Tools Image
Load가 IMAGE 생성 노드 중 앞쪽에 표시됩니다. Nodes 2.0 검색에서는 공식 검색 별칭으로
image load, input image와 이미지 로드 같은 검색어를 지원합니다. Nodes 2.0의 빈 검색
결과 순서는 ComfyUI의 사용 빈도 정책을 따릅니다.


4. 외부 폴더 이미지 사용
-------------------------
외부 폴더 기능은 ComfyUI output 폴더(생성 이미지가 저장되는 곳) 안의 폴더를 등록해,
input 폴더로 복사하거나 업로드하지 않고 현재 위치에서 직접 불러오는 기능입니다.

[2.0.2 변경] Comfy Registry(ComfyUI Manager) 보안 정책에 맞추기 위해, 등록할 수 있는
폴더를 ComfyUI output 폴더와 그 하위 폴더로 제한했습니다. 다른 드라이브나 다운로드
폴더처럼 ComfyUI 밖의 폴더는 더 이상 탐색·등록할 수 없고, 2.0.1 이하에서 등록해 둔
ComfyUI 밖의 폴더는 목록에 표시되지 않습니다. 그런 이미지는 choose file to upload로
input 폴더에 올리거나, 파일을 output 폴더 안으로 옮긴 뒤 등록해 사용하세요.
input 폴더의 이미지는 하위 폴더까지 이미 모두 표시되므로 따로 등록할 필요가 없습니다.

외부 폴더 등록 방법:

1) 노드에서 input 썸네일 보기를 누릅니다.
2) 브라우저 상단의 외부 폴더를 누릅니다.
3) + 폴더 추가를 누릅니다.
4) ComfyUI 폴더 목록에서 ComfyUI output을 선택하고 하위 폴더를 차례로 이동합니다.
5) 현재 폴더의 이미지 미리보기를 확인합니다.
6) 필요하면 표시 이름을 입력하고 이 폴더 추가를 누릅니다.

등록이 끝나면 해당 폴더와 모든 하위 폴더의 이미지가 input 이미지와 함께 썸네일·
리스트 보기에 표시됩니다. 표시 이름을 지정하지 않으면 실제 폴더 이름이 사용됩니다.
여러 외부 폴더를 등록할 수 있으며 검색, 폴더 필터, 정렬, 새로고침도 동일하게 적용됩니다.

외부 폴더 관리:

- 외부 폴더를 다시 누르면 현재 등록된 폴더를 확인할 수 있습니다.
- 등록 항목의 X를 누르면 그 폴더의 등록만 해제됩니다.
- 등록을 해제해도 실제 폴더와 이미지 파일은 이동되거나 삭제되지 않습니다.
- 같은 실제 폴더를 다시 추가해도 중복 등록되지 않습니다.
- 등록 정보는 ComfyUI 사용자 설정 폴더의 아래 파일에 저장됩니다.
  ComfyUI/user/ultra_tools/image_load_roots.json
  이 위치는 노드 폴더 밖이므로 ComfyUI Manager로 업데이트하거나 재설치해도 등록한 외부
  폴더 목록이 그대로 유지됩니다.
- 1.0.0 이하 버전에서 노드 폴더 안(ultra_tools_image_load_roots.json)에 저장되어 있던
  등록 정보는 처음 실행할 때 위 위치로 자동으로 옮겨집니다.

중요한 차이와 주의 사항:

- choose file to upload는 선택한 파일을 ComfyUI input 폴더로 업로드합니다.
- 외부 폴더 등록은 파일을 복사하지 않고 원래 경로의 파일을 직접 읽습니다.
- 등록할 수 있는 폴더는 ComfyUI output 폴더와 그 하위 폴더뿐입니다(2.0.2부터).
- output 폴더 안에 있는 바로가기(심볼릭 링크·정션)가 output 밖을 가리키면 그 대상은
  보안상 표시하거나 불러오지 않습니다.
- 외부 폴더 등록을 해제하거나 원본 폴더·파일의 위치 또는 이름을 바꾸면 그 이미지를
  선택해 둔 워크플로우가 다시 열리거나 실행될 때 파일을 찾지 못할 수 있습니다.
- 워크플로우를 다른 PC에 전달해도 외부 이미지 파일이 함께 포함되지는 않습니다.
  상대방 PC에도 같은 파일을 준비하고 해당 폴더를 다시 등록해야 합니다.
- 노드를 삭제하거나 다시 설치해도 등록 정보는 사용자 설정 폴더에 남아 있으므로, 재설치 후
  외부 폴더를 다시 등록할 필요가 없습니다.
- 로드할 때는 현재 등록된 폴더 안의 경로인지 다시 확인하며, 등록된 폴더 밖으로 벗어나는
  상대 경로는 허용하지 않습니다.


4-1. 노드를 완전히 삭제할 때 (잔여 파일 정리)
---------------------------------------------
ComfyUI Manager에서 노드를 삭제하면 comfyui-Ultra-Tools 노드 폴더만 지워집니다.
외부 폴더 등록 정보는 업데이트·재설치 때 유지되도록 노드 폴더 밖에 저장하므로,
삭제 후에도 아래 파일이 남습니다.

  ComfyUI/user/ultra_tools/image_load_roots.json

이 파일에는 등록한 폴더의 경로와 표시 이름만 들어 있으며 이미지나 개인 정보는 없습니다.
남겨 두어도 ComfyUI 동작에는 영향이 없고, 나중에 다시 설치하면 등록 목록이 그대로 복원됩니다.

흔적을 모두 지우고 싶다면 ComfyUI를 종료한 뒤 ComfyUI/user/ultra_tools 폴더를 삭제하십시오.
Windows Portable 버전에서는 보통 ComfyUI_windows_portable/ComfyUI/user/ultra_tools 입니다.

참고:
- 썸네일 캐시는 ComfyUI의 temp 폴더에 만들어지며, ComfyUI가 시작할 때 자동으로 정리합니다.
- 외부 폴더 등록을 해제하거나 이 파일을 지워도 실제 이미지 파일은 삭제되지 않습니다.


5. 언어
--------
ComfyUI 언어가 한국어이면 추가 브라우저 UI가 한글로, 그 밖의 경우에는 영문으로
표시됩니다. Core가 제공하는 image 입력, 업로드 버튼과 출력 이름의 번역도 ComfyUI의
언어 파일 체계를 따릅니다.


6. 출력
-------
IMAGE : Core Load Image와 동일한 이미지 출력
MASK  : Core Load Image와 동일한 마스크 출력

따라서 기존 Load Image의 IMAGE/MASK 연결 위치에 그대로 연결해 사용할 수 있습니다.
